---
description: Document transform is a feature that allows you to modify documents before they are used by plugins.
---

import { Callout } from '@theguild/components'

# Document Transform

Document transform is a feature that allows you to modify `documents` before they are used by plugins.
You can use functions passed to the `documentTransforms` option to make changes to GraphQL `documents`.

## Basic Usage

Document transform has `transform` function.

Let's specify an object containing those functions as the `documentTransforms` option as follows:

```ts {9-17}
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          transform: ({ documents }) => {
            // Make some changes to the documents
            return documents
          }
        }
      ]
    }
  }
}
export default config
```

For instance, to remove a `@localOnlyDirective` directive from `documents`, you can write the following code:

```ts {2, 13-22}
import type { CodegenConfig } from '@graphql-codegen/cli'
import { visit } from 'graphql'

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          transform: ({ documents }) => {
            return documents.map(documentFile => {
              documentFile.document = visit(documentFile.document, {
                Directive: {
                  leave(node) {
                    if (node.name.value === 'localOnlyDirective') return null
                  }
                }
              })
              return documentFile
            })
          }
        }
      ]
    }
  }
}
export default config
```

## How to specify by name

The document transform can also be specified by file name. You can create a custom file and pass it to `documentTransforms`.

Let's create a file named `./my-document-transform.js`:

```js
module.exports = {
  transform: ({ documents }) => {
    // Make some changes to the documents
    return documents
  }
}
```

Then, you can specify the file name as follows:

```ts {9}
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: ['./my-document-transform.js']
    }
  }
}
export default config
```

## Configuration

If you want to change the behavior of a document transform at runtime, you can simply prepare a function that generates the document transform and write the configuration in its argument.

```ts {3-10, 18}
import type { CodegenConfig } from '@graphql-codegen/cli'

const generateDocumentTransform: (config: { queryName: string }) => Types.DocumentTransformObject = ({ queryName }) => {
  return {
    transform: ({ documents }) => {
      // Modify something in documents using `queryName`.
      return documents
    }
  }
}

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [generateDocumentTransform({ queryName: 'test' })]
    }
  }
}
export default config
```

If you want to specify the document transform by file, do the following:

```ts {11-13}
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        {
          './my-document-transform.js': {
            queryName: 'test'
          }
        }
      ]
    }
  }
}
export default config
```

In this case, you can retrieve the `queryName` from the `config` argument of the `transform` function as follows:

```js
module.exports = {
  transform: ({ documents, config }) => {
    // Modify something in documents using `config.queryName`.
    return documents
  }
}
```
